Add comprehensive agentic memory API documentation for OpenSearch 3.3 #11169
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dhrubo-os
requested review from
AMoo-Miki,
dlvenable,
epugh,
kolchfa-aws,
natebower and
sumobrian
as code owners
|
Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged. Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer. When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review. |
- Add long-term memory APIs: search, update, delete - Add memory history APIs: search, delete - Add general memory APIs: get, update, delete, search by type - Update add-memory API to include data type memory and structured data - Update index with complete API structure - Support for conversation memory, data memory, and trace data - Include namespace-based organization and tagging system - Remove experimental warning as agentic memory is GA in 3.3 Signed-off-by: Dhrubo Saha <[email protected]>
|
@dhrubo-os Thank you for the PR! When you connect it to an issue, you have to leave "Closes", "Fixes", or "Resolves" so it's properly linked (in this case, |
kolchfa-aws
added
Tech review
|
Hey @dhrubo-os , let me know when this PR is ready for doc review. We have 3 days left before the release. |
- Remove redundant API files in favor of unified memory APIs - Delete legacy files: delete-long-term-memory.md, delete-memory-history.md, search-long-term-memory.md, search-memory-history.md, update-long-term-memory.md, search-memory.md, delete-memory.md, update-memory.md, get-memory.md - Enhance unified APIs with comprehensive examples for all memory types (sessions, working, long-term, history) - Add metadata field documentation to add-memory.md and get-memory-by-type.md - Update response examples and field documentation with actual API responses - Update index.md to reflect clean unified API structure - Fix memory type parameter names (sessions vs session) for consistency Signed-off-by: Dhrubo Saha <[email protected]>
- Add missing update-memory-container.md and search-memory-container.md files - Update create-memory-container.md with advanced features from Postman collection: * Multiple strategy support (SEMANTIC, USER_PREFERENCE, SUMMARY) * Strategy configuration with llm_result_path * Index configuration (index_prefix, use_system_index) * Remove experimental warning (GA in 3.3) - Remove experimental feature reference from index.md - All APIs now match actual implementation from Postman collection Signed-off-by: Dhrubo Saha <[email protected]>
- Add default llm_result_path value: $.output.message.content[0].text (Bedrock Converse format) - Document LLM connector requirement for system_prompt and user_prompt parameters - Reference ml-commons PR opensearch-project#4283 for standardized connector format - Clarify that default is optimized for Bedrock Converse API Signed-off-by: Dhrubo Saha <[email protected]>
Yes please start reviewing the PR. Thanks |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| ## Path parameters | ||
|
|
||
| | Parameter | Data type | Description | |
There was a problem hiding this comment.
Currently we have a separate column Required/Optional, can we follow the same format?
ylwu-amzn
reviewed
Oct 10, 2025
| {: .warning} | ||
|
|
||
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create a memory in one of the following modes (controlled by the `infer` parameter): | ||
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create memories in two types: |
There was a problem hiding this comment.
Suggested change
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create memories in two types: | |
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can provide memory payload in two types: |
ylwu-amzn
reviewed
Oct 10, 2025
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create a memory in one of the following modes (controlled by the `infer` parameter): | ||
| Use this API to add an agentic memory to a [memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/create-memory-container). You can create memories in two types: | ||
|
|
||
| - **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. |
There was a problem hiding this comment.
Suggested change
| - **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. | |
| - **conversational** -- Stores conversational messages between users and assistants. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| - **Conversation memory** -- Stores conversational messages between users and assistants. Can be processed (when `infer` is `true`) to extract facts or stored as raw messages. | ||
|
|
||
| - **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. |
There was a problem hiding this comment.
Suggested change
| - **Data memory** -- Stores structured, non-conversational data such as agent state, checkpoints, or reference information. | |
| - **data** -- Stores extra messages, structured, non-conversational data such as agent state, checkpoints, or reference information. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| Memory processing modes (controlled by the `infer` parameter): | ||
|
|
||
| - Fact memory -- A processed representation of the message. The large language model (LLM) associated with the memory container extracts and stores key factual information or knowledge from the original text. |
There was a problem hiding this comment.
Suggested change
| - Fact memory -- A processed representation of the message. The large language model (LLM) associated with the memory container extracts and stores key factual information or knowledge from the original text. | |
| - **infer=true** -- Use large language model (LLM) to extract key information or knowledge from the messages. |
ylwu-amzn
reviewed
Oct 10, 2025
|
|
||
| - Fact memory -- A processed representation of the message. The large language model (LLM) associated with the memory container extracts and stores key factual information or knowledge from the original text. | ||
|
|
||
| - Raw message memory -- The unprocessed message content. |
There was a problem hiding this comment.
Suggested change
| - **infer=false** -- Only store raw messages and data in working memory. |
ylwu-amzn
reviewed
Oct 10, 2025
| `session_id` | String | Optional | The session ID associated with the memory. | ||
| `agent_id` | String | Optional | The agent ID associated with the memory. | ||
| `infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true`. When `true`, the LLM extracts factual information from the original text and stores it as the memory. When `false`, the memory contains the unprocessed message and you must explicitly specify the `role` in each message. | ||
| `messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`. |
There was a problem hiding this comment.
Suggested change
| `messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`. | |
| `messages` | List | Conditional | A list of messages for conversational payload. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `payload_type` of `conversational`. |
ylwu-amzn
reviewed
Oct 10, 2025
| `agent_id` | String | Optional | The agent ID associated with the memory. | ||
| `infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true`. When `true`, the LLM extracts factual information from the original text and stores it as the memory. When `false`, the memory contains the unprocessed message and you must explicitly specify the `role` in each message. | ||
| `messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`. | ||
| `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. |
There was a problem hiding this comment.
Suggested change
| `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. | |
| `structured_data` | Map<String, Object> | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. |
There was a problem hiding this comment.
Add a new row for binary_data
ylwu-amzn
reviewed
Oct 10, 2025
| `infer` | Boolean | Optional | Controls whether the LLM infers context from messages. Default is `true`. When `true`, the LLM extracts factual information from the original text and stores it as the memory. When `false`, the memory contains the unprocessed message and you must explicitly specify the `role` in each message. | ||
| `messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`. | ||
| `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. | ||
| `memory_type` | String | Required | The type of memory: `conversation` or `data`. |
There was a problem hiding this comment.
Suggested change
| `memory_type` | String | Required | The type of memory: `conversation` or `data`. | |
| `payload_type` | String | Required | The type of payload: `conversational` or `data`. |
ylwu-amzn
reviewed
Oct 10, 2025
| `messages` | List | Conditional | A list of messages for conversation memory. Each message requires `content` and may include a `role` (commonly, `user` or `assistant`) when `infer` is set to `true`. Required for `memory_type` of `conversation`. | ||
| `structured_data` | Object | Conditional | Structured data content for data memory. Required for `memory_type` of `data`. | ||
| `memory_type` | String | Required | The type of memory: `conversation` or `data`. | ||
| `namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). |
There was a problem hiding this comment.
Suggested change
| `namespace` | Object | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). | |
| `namespace` | List<String> | Optional | Namespace context for organizing memories (e.g., `user_id`, `session_id`, `agent_id`). |
There was a problem hiding this comment.
Explain more details
If session_id not exists in namespace will create a new session and use the new session's id
|
Please fix Jekyll build failure |
Signed-off-by: Fanit Kolchina <[email protected]>
natebower
reviewed
Oct 13, 2025
_ml-commons-plugin/api/agentic-memory-apis/create-memory-container.md
Outdated
Show resolved
Hide resolved
…iner.md Signed-off-by: Nathan Bower <[email protected]>
|
@kolchfa-aws Can you resolve conflicts as well? Thanks! |
ylwu-amzn
reviewed
Oct 13, 2025
ylwu-amzn
reviewed
Oct 13, 2025
| - [Delete memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/delete-memory-container/) | ||
| - [Search memory container]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/agentic-memory-apis/search-memory-container/) | ||
|
|
||
| OpenSearch supports the following memory APIs: |
There was a problem hiding this comment.
Missed create session api ? opensearch-project/ml-commons#4246
ylwu-amzn
reviewed
Oct 13, 2025
natebower
reviewed
Oct 13, 2025
natebower
reviewed
Oct 13, 2025
Signed-off-by: Nathan Bower <[email protected]>
Co-authored-by: Yaliang Wu <[email protected]> Signed-off-by: Nathan Bower <[email protected]>
ylwu-amzn
reviewed
Oct 13, 2025
Signed-off-by: kolchfa-aws <[email protected]>
ylwu-amzn
reviewed
Oct 13, 2025
|
|
||
| ```json | ||
| DELETE /_plugins/_ml/memory_containers/{memory_container_id} | ||
| DELETE /_plugins/_ml/memory_containers/<memory_container_id> |
There was a problem hiding this comment.
This API supports two parameters
delete_all_memories: control delete all memory indices or not when delete container. Default isfalse. That means the memory index (sessions/working/long-term/history) will not be deleted when delete containerdelete_memories: array of memory types , defines deleting which memory index when delete container. Default is empty array. User can set as "delete_memories=sessions,working"
ylwu-amzn
reviewed
Oct 13, 2025
| For more information, see [Integrating ML models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/). | ||
|
|
||
| Once a memory container is created, you'll provide its `memory_container_id` to other APIs. | ||
| LLM connectors must support `system_prompt` and `user_prompt` parameters for agentic memory processing. The default `llm_result_path` is the Amazon Bedrock Converse API response path (`"$.output.message.content[0].text"`). |
There was a problem hiding this comment.
If user use OpenAI GPT model, should configure llm_result_path as "$.choices[0].message.content"
ylwu-amzn
reviewed
Oct 13, 2025
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ## Example response: Data memory |
There was a problem hiding this comment.
Suggested change
| ## Example response: Data memory | |
| ## Example response: Data payload |
ylwu-amzn
reviewed
Oct 13, 2025
| ``` | ||
| {% include copy-curl.html %} | ||
|
|
||
| ## Example response: Conversation memory |
There was a problem hiding this comment.
Suggested change
| ## Example response: Conversation memory | |
| ## Example response: Conversational payload |
ylwu-amzn
reviewed
Oct 13, 2025
| } | ||
| ``` | ||
|
|
||
| ## Example request: Storing trace data |
There was a problem hiding this comment.
Suggested change
| ## Example request: Storing trace data | |
| ## Example request: Storing tool invocation data |
* Add execute tool API doc Signed-off-by: Nathalie Jonathan <[email protected]> * Address comments Signed-off-by: Nathalie Jonathan <[email protected]> * Apply suggestions from code review Signed-off-by: Nathan Bower <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Update _ml-commons-plugin/agents-tools/tools/search-index-tool.md Signed-off-by: Nathan Bower <[email protected]> * Apply suggestions from code review Signed-off-by: kolchfa-aws <[email protected]> --------- Signed-off-by: Nathalie Jonathan <[email protected]> Signed-off-by: Nathan Bower <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: Nathan Bower <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: kolchfa-aws <[email protected]>
Signed-off-by: Dhrubo Saha <[email protected]>
Signed-off-by: Fanit Kolchina <[email protected]>
natebower
reviewed
Oct 14, 2025
_ml-commons-plugin/api/agentic-memory-apis/delete-memory-container.md
Outdated
Show resolved
Hide resolved
Signed-off-by: Nathan Bower <[email protected]>
|
@kolchfa-aws Please fix DCO |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Describe what this change achieves.
Issues Resolved
Closes #11162
Version
3.3
Frontend features
If you're submitting documentation for an OpenSearch Dashboards feature, add a video that shows how a user will interact with the UI step by step. A voiceover is optional.
Checklist
For more information on following Developer Certificate of Origin and signing off your commits, please check here.